PrizmDoc v13.0 - Updated
Viewing Sessions
API Reference > PrizmDoc Server RESTful API > Viewing Sessions

To initiate a view, the following RESTful operations should be performed as detailed in the PrizmDoc Server Sample discussion.

Available URLs

GET ViewingSession

Returns the metadata associated with a valid, active viewing session. The properties returned will be those provided in the POST request that created the viewing session.

Http Method

GET

Resource URL

/PCCIS/V1/ViewingSession/u{ViewingSessionID}

Parameters

None

Request Body

None

Response Body

If successful, this method returns the same properties and values set in the body of the POST request that created the viewing session. Additionally, the following property is included in the response:

Property Name Value Description
creationTime String A UTC-formatted time string representing the moment the viewing session was created.

Example
Copy Code 
GET http://localhost:18681/PCCIS/V1/ViewingSession/uGcIsIsEGbLV2_V9yy4NzmK2HB-JuLOH--A9sZ16cla9txO0ZDBGfq1G4kKu0r_GyEps4wWCvDwn4dpnZAR76Uw

Example Response
Copy Code 
HTTP 200
Content-Type: application/json
{
  "origin": {},
  "render": {
    "flash": {
      "optimizationLevel": 1
    },
    "html5": {
      "alwaysUseRaster": false,
      "rasterResolution": 150
    }
  },
  "password": null,
  "watermarkText": null,
  "externalId": null,
  "attachmentIndex": 0,
  "attachmentDisplayName": null,
  "tenantId": null,
  "creationTime": "2015-10-14T11:55:32.6521255Z",
  "countOfInitialPages": 0,
  "documentSource": null,
  "documentExtension": "help",
  "serverCaching": "full",
  "startConverting": null,
  "contentType": null,
  "pageContentEncryption": null,
  "watermarks": []
}

The "flash.optimizationLevel" property is kept for backward compatibility with PrizmDoc versions prior to v12.0.

 

POST ViewingSession

The first step for viewing a document is to request a viewing session Identification JSON string. The body of the request is to send useful information about the document to the PrizmDoc Server which helps identify the document that will be uploaded to the service for conversion to a web compatible viewing format. The object to be posted here is the ViewSessionProperties resource which contains several properties.  

The origin property is a key pair dictionary to contain any useful arbitrary data about the document. The PrizmDoc Server sample uses ipAddress, hostname, and sourceDocument for identification purposes, but any arbitrary data can be used that helps identify or characterizes the document.  

The render property is important for storing information for client-side rendering. It stores rendering information for the HTML5 Viewer. The Html5RenderProperties class object has properties to control aspects of SVG creation.

The externalId property and tenantId should also be set. Typically, the externalId is a unique value which makes it easier to connect items in the server log to that which is in the caller’s log but is not used for any particular purpose and the same goes for tenantId. Please look at the PrizmDoc Server sample for more information on using this RESTful API.

Http Method

POST

Resource URL

/PCCIS/V1/ViewingSession

Parameters

None

Request Body

In the request body, supply a ViewingSessionProperties resource with the following optional properties:

Property Name

Value

Description

origin

List

A list of key-value pairs containing user-specific data. This is useful for tracking information pertinent to the request, like IP address, Host Name, and any other useful bits of information.

render

Nested Object

The object that describes rendering options.

render.flash

Nested Object

Deprecated. Setting this object no longer has any effect.

render.flash.optimizationLevel

Integer

Deprecated. Setting this property no longer has any effect.

render.html5

Nested Object

The object that describes rendering options for the Viewer.

render.html5.alwaysUseRaster

Boolean

Forces PrizmDoc Server to always provide raster image data to the Viewer instead of SVG, even if the Viewer supports viewing SVG data.

render.html5.rasterResolution

Integer

Deprecated. Setting this property no longer has any effect.
render.html5.svgMaxImageSize Number

For source documents which contain images, ensures that the images in the SVG delivered to the browser do not exceed a particular pixel width and/or height. For example, a value of 8000 would ensure that any images in a PDF whose width or height were greater than 8000 pixels would be down-sampled before the image was added to the final SVG. A typical value is 8000.

The default value for this property is configurable. The out-of-box configuration uses a default value of 8000.

Use 0 to disable the optimization.
render.html5.vectorTolerance Number

For CAD documents, controls how much path simplification is allowed. The path simplification algorithm will merge points which are "close together" to create an optimized SVG. You can think of this value as defining what "close together" means. A typical value is 0.3. Higher values introduce more simplification, but also more distortion. The value cannot be greater than 10.0.

The default value for this property is configurable. The out-of-box configuration uses a default value of 0.3.

Use 0 to disable the optimization.

password

String

Specifies the password to open password-protected PDF documents.

serverCaching

String

This optional property determines whether or not the conversion output is cached for potential reuse by other viewing sessions. Valid values are:

  • "full" means that the output will be cached on the server. (default)
  • "none" means that the output will not be cached on the server.

By default, the output of the document conversion process is cached on the server for potential reuse in future viewing sessions created to view the same document. This assumes that a document is likely to be viewed multiple times across different viewing sessions. If this is not the case (e.g., a new viewing session is always a new document), you can save disk space on the server by explicitly setting the serverCaching property to "none" to prevent the caching of the output on the server.

watermarkText

String

Deprecated. Setting this property no longer has any effect.

externalId

String

If the documentSource property is set to "api", empty, or is null, this property is not used by PrizmDoc Server and can be used to store a value of your choosing for the viewing session. This value could be useful for identifying requests in PrizmDoc Server log files or other purposes you find useful.

If the documentSource property is set to "http" or "file", then this property must define the URL or local file path of the source document that PrizmDoc Server will retrieve. See the How to Transfer Your Document to PrizmDoc Server topic for more details. 

tenantId

String

This is an ID for a tenant. Tenants are not a formal concept in this system and should be monitored and maintained in the calling system. However, having this data available will allow some optional behavior. For example, with this information, it would be possible to ensure some level of isolation between tenants.

attachmentIndex

Integer

Used for documents with attachment documents, like .MSG and .EML types. Otherwise, this value will typically be 0 for other document types.

attachmentDisplayName

String

Used for documents with attachment documents, like .MSG and .EML types. Provides the display name of the attachment.

countOfInitialPages

Integer

The default value is 0, which will cause PrizmDoc Server to behave in its default manner converting all pages (running enterprise=3) of the document as soon as any page is requested. Setting countOfInitialPages to a value greater than 0 will instruct PrizmDoc Server to use two separate enterprise=3 operations: one to convert pages 0 through n-1 (where "n" the supplied value) and a second conversion to process pages "n" through the end of the document. The second conversion will only occur when content that has not been converted is requested. This should allow the first "n" pages to be created and delivered to the Viewer without forcing the entire document to be converted.

documentSource

String

This property tells PrizmDoc Server how it should expect to get the source document for a viewing session. The following values are supported:

  • "api" means that the document will be sent to PrizmDoc Server using the PUT HTTP request. This is the default and will be used if this property is null or empty.
  • "http" means that PrizmDoc Server should download the source document from the URL provided in the "externalId" property.
  • "file" means that PrizmDoc Server should create a copy of the source document from the local file path provided in the "externalId" property.

See the How to Transfer Your Document to PrizmDoc Server topic for more details.              

documentExtension

String

Defines the extension of the document specified in the externalId property. The Requirement of this property depends on whether Format Detection is enabled (default) or disabled.

If Format Detection is disabled, then this property is only required if documentSource is "http" or "file" and the file name specified in externalId does not contain a valid document extension. If the file name specified inexternalId contains a valid extension for the document, this property can be left unset.

If Format Detection is enabled (default), then this property is optional with the following restrictions:

  • If the file is uniquely identified by the Format Detection process and no documentExtension is provided, the detected documentExtension will be used. 
  • If the file is uniquely identified by the Format Detection process and a documentExtension is provided but differs from the detected documentExtension, the detected documentExtension will be used. 
If the file is not identified by the Format Detection process and a documentExtension is provided, the provided documentExtension will be used.

The preceding "." should NOT be included in the extension value, otherwise an exception will be thrown and return 500 status from the POST HTTP request.

startConverting

String

This property determines when the process to generate pages for viewing is started. This property requires that documentSource is "http" or "file" and contentType is set to a valid value. Valid values are:

  • "initialPages" means the process to generate pages for viewing is started during the initial POST /ViewingSession request.
  • "none" means the process to generate pages for viewing is started later during a request to POST /ViewingSession/{id}/Notification/SessionStarted, GET /Page or GET /PageAttributes, whichever comes first.

contentType

String

Determines the kind of content we will start pre-generating in the background so that it is ready for request more quickly. In many cases, this property is optional (though it is required if documentSource is "http" or "file" and startConverting is "initialPages").

Note that setting this property does not set the default content type for future requests for page content, nor does it limit in any way the types of content you may request. It is only a hint so that we can begin to prepare the kind of content you will likely soon request.

Valid values are:

  • "png"
  • "svg" - paths only, no inline font (not supported in IE8)
  • "svga" - paths optimized with an inline font (not supported in IE8, IE10)
  • "svgb" - paths further optimized with an inline font (not supported in IE8, IE9, IE10, desktop Safari 9.x or Chrome on Windows)
serverSideSearch String

This property determines whether server-side text searching will be available for a document.

Valid values are:

  • "disabled" - server-side search will not be available for the viewing session.
  • "enabled" - server-side search will be available for the viewing session. (default)

When enabled at viewing session creation, large document text retrieval and server-side searching via the search task API will be available. If disabled, requests to the search task API will result in an error.

See the Search Tasks topic for more details.
minSecondsAvailable Integer

This optional property defines the amount of time in seconds for the viewingSession being created to be kept alive. The value is applicable only to viewing sessions created with the POST /ViewingSession request. A value of zero means the configured viewing session timeout value is used. The default viewingSession timeout is 20m (1200 seconds). This property is validated against the value set for viewing.sessionConstraints.minSecondsAvailable.max in the central configuration file.

When the serverCaching property is set to "full" and this property is provided, it must be 0 or a validation error will result. When the serverCaching property is set to "none" this property may be any positive integer up to viewing.sessionContraints.minSecondsAvailable.max. If the value is less than the default viewing.sessionLifetime it will be set to the default viewing.sessionLifetime (20m).
watermarks Array The array of objects which describe the watermarks to apply to the viewing session. This object is optional. The presence of valid watermark objects enables watermarking for the viewing session.
watermarks[n].type String

This property determines the type of watermark this object defines. The value of this property will determine what remaining properties are important according to the type.

Valid values:

  • "text" means that the current watermark object defines a watermark that will display horizontal text on all pages in the viewing session.
  • "diagonalText" means that the current watermark object defines a watermark that will display diagonal text on all pages in the viewing session.
  • "image" means that the current watermark object defines a watermark that will display an image on all pages in the viewing session.
Default value: N/A, this property is required.
watermarks[n].opacity Number

This property determines how transparent or opaque a watermark appears over the page content. A value of 0.0 is completely transparent (not visible). A value of 1.0 is completely opaque.

Valid values: 0.0 to 1.0

Default value: 1.0
watermarks[n].text String

This property determines the text string that will be displayed for "text" and "diagonalText" watermark types. This should not be set for "image" watermark types.

Valid values: Any valid text string

Default value: N/A, this property is required when type is "text" or "diagonalText".

See the How to Watermark Content in a Viewing Session topic for more information about special properties of the text string.
watermarks[n].color String

This property determines the color of the text that will be displayed for "text" and "diagonalText" watermark types. This should not be set for "image" watermark types.

Valid values: Any valid CSS color name (i.e. "red", "darkblue") or HEX value ("#FF0000")

Default value: "black"
watermarks[n].fontFamily String

This property determines the font name of the text that will be displayed for "text" and "diagonalText" watermark types. This should not be set for "image" watermark types.

Valid values; Any valid font family name

Default: Browser default font

See the How to Watermark Content in a Viewing Session topic for more information about the use of fonts.
watermarks[n].fontSize String

This property determines the font size of the text that will be displayed for "text" and "diagonalText" watermark types. This should not be set for "image" watermark types.

Valid values: A string containing a positive, non-zero decimal number followed by "pt" (i.e. "27.5pt").

Default value: "12pt"
watermarks[n].fontStyle String

This property determines the style of the text that will be displayed for "text" and "diagonalText" watermark types. This should not be set for "image" watermark types.

Valid values:

  • "normal" means that the  text will have no additional styling applied.
  • "italic" means that the text will be italicized.

Default value: "normal"
watermarks[n].fontWeight String

This property determines the weight of the text that will be displayed for "text" and "diagonalText" watermark types. This should not be set for "image" watermark types.

Valid Values:

  • "normal" means that the  text will be a normal weight.
  • "bold" means that the text will be bold weight.
Default value: "normal"
watermarks[n].textDecoration String

This property determines the decoration applied to the text that will be displayed for "text" and "diagonalText" watermark types. This should not be set for "image" watermark types.

Valid Values:

  • "none" means that the  text will have no additional decoration.
  • "underlined" means that the text will be underlined.
Default value: "none"
watermarks[n].horizontalAlign String

This property determines the horizontal alignment within the page for "text" and "image" watermark types. This property does not apply to "diagonalText" watermarks. For "left" and "right" values, sensible margins will be used so that the edge of the watermark does not fall on the very edge of the page.

Valid Values:

  • "left" means that the  watermark will be aligned on the left side of the page. Further, multi-line text watermarks will also have left alignment.
  • "center" means that the  watermark will be aligned on the center of the page. Further, multi-line text watermarks will also have center alignment.
  • "right" means that the  watermark will be aligned on the right side of the page. Further, multi-line text watermarks will also have right alignment.

Default value: "center"
watermarks[n].verticalAlign String

This property determines the vertical alignment within the page for "text" and "image" watermark types. This property does not apply to "diagonalText" watermarks. For "top" and "bottom" values, sensible margins will be used so that the edge of the watermark does not fall on the very edge of the page.

Valid Values:

  • "top" means that the  watermark will be aligned on the top of the page.
  • "middle" means that the  watermark will be aligned on the middle of the page.
  • "bottom" means that the  watermark will be aligned on the bottom of the page.

Default value: "middle"
watermarks[n].slope String

This property determines the angle that the text is drawn for "diagonalText" watermark types. This should not be set for "image" and "text" watermark types.

Valid Values:

  • "up" means that the  diagonal text will start in the lower-left corner of the page and extend to the upper-right corner of the page.
  • "down" means that the  diagonal text will start in the upper-left corner of the page and extend to the lower-right corner of the page.
Default value: "up"
watermarks[n].autoSize String

This property determines how an "image" watermark type will be sized to fill a page. If specified, any values for scale, verticalAlign, and horizontalAlign will be ignored. Note that the sensible automatic margins mentioned above for verticalAlign and horizontalAlign do not apply when auto-sizing an image watermark. In this case, the image should reach the very edge of the page. This should not be set for "text" and "diagonalText" watermark types.

Valid Values:

  • "fit" means the image is scaled as far as possible while maintaining aspect ratio and without allowing any of the image to go beyond the edge of the page.
  • "fill" means the image is scaled so that it completely fills the entire page with aspect ratio maintained. Some of the image may fall off the edge of the page, but the entire page is guaranteed to be covered by some part of the image.
  • "stretch" means the image is resized to be the same as the page. Aspect ratio is ignored.

Default value: N/A, the scale, verticalAlign, and horizontalAlign properties will be used if unset.
watermarks[n].scale Number

This property determines the size of images that are located using the verticalAlign and/or horizontalAlign properties. A scale value may be specified as a numeric value between 0.0 and 1.0. The value 1.0 indicates the image will be scaled to the size of the page and 0.0 indicates the image will be scaled infinitesimally small and will not be rendered. This should not be set for "text" and "diagonalText" watermark types.

Valid values: 0.0 to 1.0

Default value: 0.25 as long as autoSize is not set.
watermarks[n].src String

This property determines the source of the image data for "image" watermark types. This should not be set for "text" and "diagonalText" watermark types.

Note: The image watermark source must be a PNG. If other image formats are provided it will cause invalid watermarks to be created.

Valid values:

  • A work file ID referencing a valid work file. See the Work File topic for more information about creating work files and obtaining their IDs.
  • A URL specifying an absolute location with an HTTP or HTTPS scheme. This URL must be accessible from the server hosting the PrizmDoc RESTful Web Services.
Default value: N/A, required for "image" watermark types.
pageContentEncryption String

Allows content encryption to be enabled or disabled for a single viewing session, overriding the PrizmDoc Server configuration on the server. See the "viewing.contentEncryption.enabled" setting in the Central Configuration Options topic for more details about enabling or disabling content encryption on the server. 

Valid values for this property are:

  • "enabled" means that the server will encrypt page content in the responses for the current viewing session. This value will override the PrizmDoc Server configuration setting.
  • "disabled" means that the server will NOT encrypt page content in the responses for the current viewing session. This value will override the PrizmDoc Server configuration setting.
  • "default" means that the PrizmDoc Server configuration setting will be used to determine whether or not it encrypts page content in the responses for the current viewing session. This is the default behavior.

Setting this property to null or not including it at all means the same as "default".

See the topic Enabling Content Encryption for more information about this feature.

 Additionally, the server configuration setting "viewing.sessionConstraints.pageContentEncryption.allowedValues" can be used to limit the values of this property that the server will accept. A value outside of the acceptable values defined by this server configuration setting will cause an error and the viewing session will not be created. See the "viewing.sessionConstraints.pageContentEncryption.allowedValues" setting in the Central Configuration Options topic for more details about defining allowable values for this property.    

Response Body

If successful, this method returns the following properties:

Property Name

Value

Description

viewingSessionId

String

The ID for this new viewing session.
affinityToken String The affinity token associated with this new viewing session, if PrizmDoc is running in Multi-Server Mode.

Example
Copy Code 
POST http://localhost:18681/PCCIS/V1/ViewingSession

Example
Copy Code 
POST http://localhost:18681/PCCIS/V1/ViewingSession
Content-Type: application/json
{
    "tenantId": "my application name",
    "externalId": "my-unique-document-name.docx",
    "render": {
        "html5": {
            "alwaysUseRaster": false
        }
    },
    "minSecondsAvailable": 1500,
    "watermarks": [
        {
            "type": "text",
            "opacity": 0.6,
            "text": "jdoe\n67.79.169.114\n11/13/2014 2:24 PM\NOT FOR DISTRIBUTION",
            "color": "red",
            "fontFamily": "Consolas",
            "fontSize": "16pt",
            "fontWeight": "bold",
            "verticalAlign": "bottom",
            "horizontalAlign": "right"
        }
    ]
}

 

Example Successful Response
Copy Code 
{
    "viewingSessionId":"8091681f-15bf-4150-94a0-3ff7f2acd42d"
    "affinityToken":" S2ZqtGi9vUAXBgdmM/PNNpCM4CApe9NxLIp/4QnAHlg="
}

Examples of Errors Related to the minSecondsAvailable Property

Scenario when central configuration file contains: viewing.sessionConstraints.minSecondsAvalable.max: 1500 

Example
Copy Code 
POST http://localhost:18681/PCCIS/V1/ViewingSession
Content-Type: application/json
{
    "tenantId": "my application name",
    "externalId": "my-unique-document-name.docx",
    "minSecondsAvailable": 3500
}

 

Example Error Response
Copy Code 
HTTP 480 InvalidInput
{
 "errorCode": "InvalidInput".
 "errorDetails": {
      "in": "body",
      "at": "minSecondsAvailable",
      "expected": {
           "type": "integer",
           "greaterThanOrEqualTo":0,
           "lessThanOrEqualTo": 1500
       }
   }
}

 Scenario when serverCaching is set to "full": viewing.sessionConstraints.minSecondsAvalable.max: 1500

Example
Copy Code 
POST http://localhost:18681/PCCIS/V1/ViewingSession
Content-Type: application/json
{
     "tenantId": "my application name",
     "externalId": "my-unique-document-name.docx",
     "minSecondsAvailable": 500,
     "serverCaching": "full"
}

 

Example Error Response
Copy Code 
HTTP 480 InputNotSupportedWithServerCachingEnabled
{
  "errorCode": "InputNotSupportedWithServerCachingEnabled".
  "errorDetails": {
       "in": "body",
       "at": "minSecondsAvailable",
  }
}

 

DELETE ViewingSession/u{ViewingSessionID}

This RESTful API requests the PrizmDoc Server service to delete the viewing session.

Http Method

DELETE

Resource URL

/PCCIS/V1/ViewingSession/u{ViewingSessionID}

Parameters

ViewingSessionID The ID of the viewing session associated with the request.

Request Body

None.

Example
Copy Code 
DELETE http://localhost:18681/PCCIS/V1/ViewingSession/u8091681f-15bf-4150-94a0-3ff7f2acd42d

Response

When a DELETE request is made for a viewing session with serverCaching set to "none".

Example
Copy Code 
HTTP 204

When a DELETE request is made for a viewing session which does not exist.

Example
Copy Code 
HTTP 404

When a DELETE request is made for a viewing session with serverCaching set to "full".

Example
Copy Code 
HTTP 580
Content-Type: application/json
{
     "errorCode": "CannotDeleteCachedViewingSession"
}

 

PUT ViewingSession/u{ViewingSessionId}/SourceFile?FileExtension={FileExtension}

Uploads the source document to be viewed.

Request

URL Parameters

Parameter Description
{ViewingSessionId} The viewingSessionId provided in the response from POST /ViewingSession.
{FileExtension} File extension of the document being uploaded. This parameter may or may not be required depending on the file type and whether Format Detection is enabled. Note that the extension must not include the leading period (for example, 'jpg' is accepted but '.jpg' will return a 400 HTTP status). Extensions are not case sensitive. If Format Detection is disabled, the FileExtension must be provided.
If Format Detection is enabled (the default), the use of FileExtension is as follows:

Request Body

The bytes of the source document.

Successful Response

A simple HTTP 200 status code indicating the file was received.

Error Responses

Status Code JSON errorCode Description
480 "IncorrectUsage" For any new viewing session, you can give it either 1) a single source document for viewing or 2) two documents (original and revised) which should be viewed as a comparison, but you cannot do both. If you receive this error from this URL, it is because one or more files (original and/or revised) have already been provided for comparison.

Examples

Request

Example
Copy Code 
PUT http://localhost:18681/PCCIS/V1/ViewingSession/uXYZ.../SourceFile?FileExtension=doc

<<file bytes>>

Successful Response

Example
Copy Code 
HTTP/1.1 200 OK

 

PUT /v2/viewingSessions/{viewingSessionId}/sourceFile/original

Used when viewing a comparison of two documents, uploads the first of the two documents; the original document.

Request

URL Parameters

Parameter Description
{viewingSessionId} The viewingSessionId provided in the response from POST /ViewingSession.

Request Body

The bytes of the original document (for comparison with a revised document).

Successful Response

A simple HTTP 200 status code indicating the file was received.

Error Responses

Status Code JSON errorCode Description
404 - No viewing session with the provided viewingSessionId could be found.
480 "MissingInput" A required input value was not provided. See errorDetails in the response body.
480 "InvalidInput" An invalid input value was used. See errorDetails in the response body.
480 "CannotChangeDocument"

The viewing session already has an original document assigned.
480 "UnsupportedFormatForComparison" The uploaded file was not a Word document (for comparison viewing, we currently only support "doc" and "docx" files).
480 "IncorrectUsage" For any new viewing session, you can give it either 1) a single source document for viewing or 2) two documents (original and revised) which should be viewed as a comparison, but you cannot do both. If you receive this error from this URL, it is because a single source document has already been provided.
480 "FeatureNotLicensed"

The server's license does not allow the use of the MSO (Microsoft Office) feature, so document comparison is not possible.
480 "FeatureDisabled" The server has not been configured to allow the use of the Microsoft Office renderer, so document comparison is not possible.

Examples

Request

Example Title
Copy Code 
PUT http://localhost:18681/v2/viewingSessions/XYZ.../sourceFile/original

<<file bytes>>

Successful Response

Example
Copy Code 
HTTP/1.1 200 OK

 

 

PUT /v2/viewingSessions/{viewingSessionId}/sourceFile/revised

Used when viewing a comparison of two documents; uploads the second of the two documents, the revised document.

Request

URL Parameters

Parameter Description
{viewingSessionId} The viewingSessionId provided in the response from POST /ViewingSession.

Request Body

The bytes of the revised document (for comparison with an original document).

Successful Response

A simple HTTP 200 status code indicating the file was received.

Error Responses

Status Code JSON errorCode Description
404 - No viewing session with the provided viewingSessionId could be found.
480 "MissingInput" A required input value was not provided. See errorDetails in the response body.
480 "InvalidInput" An invalid input value was used. See errorDetails in the response body.
480 "CannotChangeDocument" The viewing session already has an original document assigned.
480 "UnsupportedFormatForComparison" The uploaded file was not a Word document (for comparison viewing, we currently only support "doc" and "docx" files).
480 "IncorrectUsage" For any new viewing session, you can give it either 1) a single source document for viewing or 2) two documents (original and revised) which should be viewed as a comparison, but you cannot do both. If you receive this error from this URL, it is because a single source document has already been provided.
480 "FeatureNotLicensed" The server's license does not allow the use of the MSO (Microsoft Office) feature, so document comparison is not possible.
480 "FeatureDisabled" The server has not been configured to allow the use of the Microsoft Office renderer, so document comparison is not possible.

Examples

Request

Example
Copy Code 
PUT http://localhost:18681/v2/viewingSessions/XYZ.../sourceFile/revised

<<file bytes>>

Successful Response

Example
Copy Code 
HTTP/1.1 200 OK

GET ViewingSession/u{ViewingSessionID}/SourceFile?ContentDispositionFilename={ContentDispositionFilename}

Gets the source document in use for a viewing session. The document returned will be an identical copy of the document originally provided; no conversions to other formats are supported.

The response will set the Content-Type header to the most-specific MIME type it can or application/octet-stream otherwise.

Request

URL Parameters

Parameter Description
{ViewingSessionId} The viewingSessionId provided in the response from POST /ViewingSession.
{ContentDispositionFilename} Name to use for the filename attribute in the Content-Disposition response header. By default, the value will be SourceFile.<ext>, where <ext>is the appropriate file extension (such as doc or docx).

Response

The raw bytes of the viewing session's source document.

Example

Request

Example
Copy Code 
GET http://localhost:18681/PCCIS/V1/ViewingSession/uXYZ.../SourceFile?ContentDispositionFilename=MonthlySalesReport

Response

Example
Copy Code 
200 OK
Content-Type: application/msword
Content-Disposition: attachment; filename=MonthlySalesReport.pdf

<<file bytes>>
 

GET /v2/viewingSessions/{viewingSessionId}/sourceFile/original?contentDispositionFilename={contentDispositionFilename}

When viewing a comparison of two documents, gets the original document used in the comparison. The document returned will be an identical copy of the document originally provided; no conversions to other formats are supported.

The response will set the Content-Type header to the most-specific MIME type it can or application/octet-stream otherwise.

Request

URL Parameters

Parameter Description
{viewingSessionId} The viewingSessionId provided in the response from POST /ViewingSession.
{contentDispositionFilename} Name to use for the filename attribute in the Content-Disposition response header. By default, the value will be OriginalSourceFile.<ext>, where <ext> is the appropriate file extension (such as doc or docx).

Successful Response

The raw bytes of the first of the two documents being viewed as a comparison; the original document.

Error Responses

Status Code JSON errorCode Description
404 - No viewing session with the provided viewingSessionId could be found.
480 
"DocumentNotProvidedYet"
An original document has not been associated with the viewing session yet.
480 
"IncorrectUsage"
For any new viewing session, you can give it either 1) a single source document for viewing or 2) two documents (original and revised) which should be viewed as a comparison, but you cannot do both. If you receive this error from this URL, it is because a single source document was provided for viewing, so there will never be an original comparison document to get.

Examples

Request

Example
Copy Code 
GET http://localhost:18681/v2/viewingSessions/XYZ.../sourceFile/original?contentDispositionFilename=OldMonthlySalesReport

Successful Response

Example
Copy Code 
200 OK
Content-Type: application/msword
Content-Disposition: attachment; filename=OldMonthlySalesReport.docx

<<file bytes>>

GET /v2/viewingSessions/{viewingSessionId}/sourceFile/revised?contentDispositionFilename={contentDispositionFilename}

When viewing a comparison of two documents, gets the revised document used in the comparison. The document returned will be an identical copy of the document originally provided; no conversions to other formats are supported.

The response will set the Content-Type header to the most-specific MIME type it can or application/octet-stream otherwise.

Request

URL Parameters

Parameter Description
{viewingSessionId} The viewingSessionId provided in the response from POST /ViewingSession.
{contentDispositionFilename} Name to use for the filename attribute in the Content-Disposition response header. By default, the value will be RevisedSourceFile.<ext>, where <ext> is the appropriate file extension (such as doc or docx).

Successful Response

The raw bytes of the second of the two documents being viewed as a comparison, the revised document.

Error Responses

Status Code JSON errorCode Description
404 - No viewing session with the provided viewingSessionId could be found.
480 
"DocumentNotProvidedYet"
A revised document has not been associated with the viewing session yet.
480 
"IncorrectUsage"
For any new viewing session, you can give it either 1) a single source document for viewing or 2) two documents (original and revised) which should be viewed as a comparison, but you cannot do both. If you receive this error from this URL, it is because a single source document was provided for viewing, so there will never be a revised comparison document to get.

Example

Request

Example
Copy Code 
GET http://localhost:18681/v2/viewingSessions/XYZ.../sourceFile/revised?contentDispositionFilename=NewMonthlySalesReport

Successful Response

Example
Copy Code 
HTTP/1.1 200 OK
Content-Type: application/msword
Content-Disposition: attachment; filename=NewMonthlySalesReport.docx

<<file bytes>>

POST ViewingSession/u{ViewingSessionID}/Notification/SessionStarted

This RESTful API requests the PrizmDoc Server service to begin conversion of the document to HTML format. The object property, viewer, will be set to "HTML5".

The User-Agent header should be set to an appropriate browser string to enable the PrizmDoc Server to begin generating the correct content for the Viewer.

Http Method

POST

Resource URL

/PCCIS/V1/ViewingSession/u{ViewingSessionID}/Notification/SessionStarted

Parameters

ViewingSessionID The ID of the viewing session associated with the request.

Request Body

In the request body, supply an object with the following optional property:

Property Name Value Description
viewer String

Specify the type of viewer being used. The only supported value is "HTML5".

The default value is "HTML5".

Response Body

Empty.

Example
Copy Code 
POST http://localhost:18681/PCCIS/V1/ViewingSession/u8091681f-15bf-4150-94a0-3ff7f2acd42d/Notification/SessionStarted
Example Title
Copy Code 
Empty

 

POST ViewingSession/u{ViewingSessionID}/Notification/SessionStopped

This request is used to stop, or invalidate, an active viewing session. This can be useful in situations when a viewing session is started but something prevents the document from being uploaded to the PrizmDoc RESTful Web Services successfully. You may also have a need in your application to stop a viewing session after a user is done with it and before the viewing session expires.

The parameters provided in the body of the request should be set with some consideration within your application. The httpStatus and endUserMessage property values specified in the body of this request will determine the HTTP status code and reason phrase that will be returned in the response for any request of the viewing session once this request has been issued.

For example, if this request is sent with httpStatus = 504 and endUserMessage = "Session is no longer available" and then a request is made to get page 0 for the same viewing session, the response status of that request will be 504 Session is no longer available and the page content will not be delivered.

This allows you to explicitly handle the error case when requests are sent after the session has been stopped. 

Http Method

POST

Resource URL

/PCCIS/V1/ViewingSession/u{ViewingSessionID}/Notification/SessionStopped

Parameters

ViewingSessionID

The ID of the viewing session associated with the request.

Request Body

In the request body, optionally supply a SessionStoppedProperties resource with the following optional properties:

Property Name Value Description
endUserMessage String A message suitable for display to the end user to be returned if any attempt to use the session is made after the session has been stopped. Default is "Session is stopped".
httpStatus Integer The http status suitable for display to the end user to be returned if any attempt to use the session is made after the session has been stopped. Default is 580.
accusoftErrorNumber Integer A custom Accusoft error number that should be sent back to the end user to be returned if any attempt to use the session is made after the session has been stopped. Default is 580.
serverLogMessage String A message that should be placed into the server's log file when the session is stopped. Default is "The viewing session is stopped on request from the client".

Response Body

Empty.

Example
Copy Code 
POST http://localhost:18681/PCCIS/V1/ViewingSession/u8091681f-15bf-4150-94a0-3ff7f2acd42d/Notification/SessionStopped
{
  "endUserMessage": "Session no longer available",
  "httpStatus": 504,
}

 

Example Response
Copy Code 
200 OK

 

PUT /PCCIS/V1/ViewingSession/u{id}/SourceRef

Assigns a source reference for this viewing session. This can be a single existing work file to be used as the source document, or a pair of work files to be used for comparison. Using a source reference can be particularly useful when you want to avoid repeatedly uploading the same source file to the back end.

Request

Request Headers

Name Description
Content-Type Must be application/json

URL Parameters

Name Description
{viewingSessionId}

The viewingSessionId provided in the response from POST /ViewingSession

Request Body when assigning reference for a single document

Request Body when comparing two documents

Successful Response

A simple HTTP 200 status code.

Error Responses

Status Code JSON errorCode Description
480 "MissingInput" A required input value was not provided. See errorDetails in the response body.
480 "InvalidInput" An invalid input value was used. See errorDetails in the response body.
480 "NotFound" The work file has expired or does not exist. See errorDetails in the response body.
480 "CannotChangeDocument" The viewing session already has a source document assigned. See errorDetails in the response body.
480 "UnsupportedFormatForComparison" One of the files provided for comparison was not a Word document (for comparison viewing, we currently only support "doc" or "docx" files. See errorDetails in the response body.
480 "IncorrectUsage" For any new viewing session, you can give it either 1) a single source document for viewing or 2) two documents (original and revised) which should be viewed as a comparison, but you cannot do both. If you have already provided a source document and then attempt to provide an original and revised document pair, or vice versa, you will receive this error.
480 "FeatureNotLicensed"

The server's license does not allow the use of the MSO (Microsoft Office) feature, so document comparison is not possible.
480 "FeatureDisabled" The server has not been configured to allow the use of the Microsoft Office renderer, so document comparison is not possible.

Examples

Assigning reference for a single document

Example
Copy Code 
PUT /PCCIS/V1/ViewingSession/u{id}/SourceRef
Content-Type: application/json
{
   "refType": "workFile",
   "fileId": "CVBuD7DbQYNoJDqByGierQ",
}

 

Example
Copy Code 
HTTP/1.1 200 OK

Assigning two documents to be viewed as a comparison

Example
Copy Code 
PUT /PCCIS/V1/ViewingSession/u{id}/SourceRef
Content-Type: application/json
{
    "refType": "comparison",
    "original": {
       "refType": "workFile",
       "fileId": "CVBuD7DbQYNoJDqByGierQ",
    },
    "revised": {
       "refType": "workFile",
       "fileId": "5qTYa3gzN9gYUb5SzqUhqg",
    }
}

 

Example
Copy Code 
HTTP/1.1 200 OK

 

GET /PCCIS/V1/ViewingSession/u{id}/FileId

Returns the id of the work file which is being used for this viewing session. 

Regardless of how a source document is provided, whether it is uploaded directly or whether an existing work file is used by reference, once the viewing engine has acquired the source document it will first ensure that a copy of it is present in the work file system.

Getting the work file id for a viewing session can be particularly helpful if you have uploaded a file directly to a viewing session and then want to reuse that file for a new viewing session without uploading it again.

Request

Query Parameters

None

Request Headers

None

Response

HTTP Status Codes

200

480 - When a document has not been provided yet.

Response Headers

Name

Description

Content-Type

Will be set to "application/json".

Response Body

When a source document exists:

As long as this viewing session has a source document, the response will contain a work file id:

Example
Copy Code 
HTTP 200
Content-Type: application/json
{
      "fileId": "mUiXiqsQuevJKO9Swa32Bd"
}

When a source document has not been provided:

If you just created a viewing session and have not yet provided a source document (either by upload or reference), then this URL will respond with:

Example
Copy Code 
HTTP 480
Content-Type: application/json
{
      "errorCode": "DocumentNotProvidedYet",
      "errorDetails": {
          "in": "body",
          "at": "fileId"
      }
}

 

 

©2017. Accusoft Corporation. All Rights Reserved.

Send Feedback